This describes some simple ways to run one or many simulations on a computer. You must have access to the unix-style command line:

on Mac OS X, open Applications/Utilities/Terminal
go to the directory where the executable and parameter file are located.

If the directory is named run:

cd run

Live Run

Usually, you need to specify the full path of the executable. If play is present in the current directory, you must type:

./play live

this should open a window and start a live simulation using config.cym. You can specify another configuration file:

./play live spindle.cym

By configuring your PATH to include the directory where the executable is located, you may be able to just type:

play live

Normal Run

The canonical way to use cytosim is to call sim to calculate a simulation, and then play to display the results once sim has finished:

./sim

./play

This will use the configuration config.cym in the current directory.

If you do not want to wait until sim returns, you can run sim in the background:

./sim&

You can use play to display the results at any time, even if the simulation is not completed.

Overnight Run

You should not run two simulations in the same directory, because the output files are always named in the same way. Hence you should normally always run cytosim in a separate directory.

In addition, if the calculation is more than a few minutes, you should probably use nohup to prevent the simulation from being automatically terminated when you log out from the session:

Here is the code that illustrates the two techniques:

mkdir run0000
cp config.cym run0000/.
cd run0000
nohup ../sim&

To do this, it is even better to use the script /python/run/start.py, because it will automatically create the new directory, and start the simulation:

start.py sim config.cym

You can call start.py many times, and the new directories will be named run0000, run0001, etc.

Visual Inspection

Now that you have many completed simulations, you will want to look at them, and a few python scripts in /python/look can help you to do this:

Script	Typical usage
`make_image.py`	make one image in each `run` directory
`make_movie.py`	make a movie in each `run` directory
`makeHTML.py`	make a HTML page `frame.html` to view all the images
`scan.py`	run a command in multiple directories

Examples:

Create HTML directory with a single image

make_image.py 'play window_size=1024,128 frame=100' run*

makeHTML.py

Create HTML directory with images every 100 frame:

scan.py '../play movie period=100 size=256 auto_scale=0 zoom=6 label={}' run*

makeHTML.py

Open frame.html to view the results.

Analysis

You can also analyse the runs in a more automated way:

Program	Typical usage
`report`	generate one data file in each `run` directory
`get_data.py`	collect data from the `run` diretories into one master file
matlab	read the master file and make a plot

Cytosim's tool report will generate some output from the trajectory file of a completed simulation. You may use scan.py to analyse a set of directories. It is however generally better to include some reporting directly into the config file, with the command write.

The tools and python scripts should be able provide up-to-date help:

submit.py help

analyse help

Conversion

With sim, it is possible to extract a frame from a binary trajectory file, and export it in the text-only format. Simply execute a following config file with for example:

include properties.cmo
read objects.cmo { frame = 10 }
write state objects.txt { binary=0 }